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Summary 

People writing software want to be able to do Macintosh-like graphics in the Super Hi-Res 
Graphics modes. 1 To do this we need QuickDraw like routines for the new modes. Most 
of the code that provides this facility is in ROM; other parts will be in RAM (Because of the 
way the tools system works an application need not care what part of the code is where.). 
The ROM routines combined with these RAM based extensions are what we call 
QuickDraw II. 

Appendix C contains a comparison of QuickDraw with QuickDraw H 

QuickDraw II Capabilities 

The Quick Draw II core routines include calls for manipulating the graphics environment 
and drawing primitive graphical objects. Included in the graphics environment is 
information about 

Drawing Location 
Coordinate System 
Clipping 

The primitive objects supported are 

Lines Ovals 

Rectangles RoundRects 

Regions Arcs 

Polygons 

Pixel Images 
Text 

The first group of objects (lines, rectangles, regions, polygons, ovals, roundrects and arcs) 
are all drawn with patterns. A pattern is a 64-pixel image organized as an 8x8 pixel square 
which is used to define a repeating design. When a pattern is drawn, it is aligned such that 
adjacent areas of the same pattern in the same graphics port will blend with it into a 
continuous, coordinated pattern. In addition to the pattern, lines, regions and rectangles are 
drawn using a drawing mask. The drawing mask is an 8x8 bit square that represents a 
repeating design that is used to mask the pattern as it is drawn. Only those pixels in the 
pattern aligned with a "1" in the mask are drawn. See figure 0 below. 


1 These are new modes found only on a Cortland computer and have no relationship to 
existing Apple II modes. The hardware is summarized in Appendix B for those not 
familiar with it 
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Figure 0 
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Note that drawing with a mask that is all "1" is like drawing without masking occuring at 
alL Drawing with a mask of all "0” is like not drawing since aU pixels are masked out 

The QuickDraw II support for Pixel Maps is similar to Macintosh QuickDraw support for 
bit maps. The major difference is that pixels are not a single bit An additional difference 
is that code in ROM does not support stretching and compression of an image as it is 
transfered from one to pixel map to another. 

The QuickDraw II support for Text is similar to the text support on the Macintosh but not 
identical. Major differences include 

QuickDraw II only supports a limited number of style modifcations 
The Font Manager is not closely integrated with QuickDraw IL It is more of a 
higher level tool so the interaction between the two is different 
, QuickDraw II does not scale text 

Basic Concepts and Terminology 

A pixel map is an area of memory containing a graphic image (the analogous QuickDraw 
term is Bithnage). This image is organized as a rectangular grid of dots called picture 
elements, or pixels. Each Pixel has an assigned value or color. The number of colors a 
pixel may have depends on its size or chunkiness. Two sizes are possible: four-color and 
sixteen-color. Exactly which colors map into the various pixel values is determined by a 
color table. This will be described later. 

Pixel Size in the display is controlled independently for each scan line. Each scan line has a 
scan line control byte (SCB) which determines the scan line's properties. See Appendix B 
for more details. 

Pixels are frequently thought of as points in the Cartesian coordinate system, with each 
pixel assigned a horizontal and vertical coordinate. Following the QuickDraw standard, the 
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coordinate grid falls between, rather than on pixels (see Figure 1). Each pixel is associated 
with the point that is above and to the left of it. 

Figure 1 

Pixels, Points and Rectangles 
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The rectangle is defined by 
the points (2,1) and (7,7). 

It encloses 30 pixels. 

A pixel 

4 " A Point 



A Rectangle 


This scheme allows a rectangle to divide pixels into two classes: those which fall within the 
rectangle and those which fall outside the rectangle. Calls which draw.rectanglesjanly 
whigh fal l U-Tside-th.<S..re„Qm!l^l<S- 

A pixel map need not be the area of memory associated with the graphics screen. 
QuickDraw n can treat other memory as pixel map memory and draw into it as easily as the 
screen memory. 

Drawing can be done in coordinates appropriate to the data being used. Data is mapped 
from drawing space to the pixel map according to the information kept in two rectangles 
(see Figure 2): 

a. The Bounds Rectangle 

b. The Port Rectangle 

An important point to note is that the conceptual drawing space for QuickDraw II is not the 
same as for QuickDraw on the Macintosh. On the Macintosh the drawing space is 64K by 
64K pixels centered around 0,0. The bounds of the drawing space is -32K,-32k and 
32K32K. In QuickDraw II the drawing space is only 32K by 32K pixels. The bounds of 
drawing are -16K,-16K and 16K,16K. Commands to draw oudside this space will 
produce unpredicmbleiesults. They will not eeneratejenam. 


QuickDraw IIERS 


August 11,1986 


Page 4 











Figure 2. The Bounds and Port Rectangles 



MM Active Port Ron (intersection of the BoundsRect 

and PortRect) 


The BoundsRect is a rectangle that encompasses the entire pixel map. The upper left hand 
comer of the Bounds rect is the point that is above and to the left of the first pixel in the 
pixel map. 

The PortRect is a rectangle that describes the "active" region of the pixel map. The 
intersection of the Port and Bounds rects is the only place that pixels in the pixel map will 
change (ignoring the VisRgn and ClipRgn to be discussed later). 

A SetOrigin call allows you to change the position of both these rectangles in the coordinate 
plane. The rectangles remain the same size and in the same location relative to each other 
but the upper left hand comer (the origin) of the PortRect is set to the point passed by 
SetOrigin. 

Drawing is the process by which pixels are altered in a pixel map. You may imagine a pen 
drawing the image by placing dots of the appropriate color at each pixel which falls under 
its path as specified by the program. 

Drawings are clipped when instructions to draw in inactive parts of the drawing space are 
ignored. For example, if I am clipping to a rectangle defined by (100,100) and (200,200) 
and I try to draw a line from (0,0) to (1000,1000), only the pixels that fall inside the 
(100,100) thru (200,200) range are affected 


QuickDraw II also provides for clipping to arbitrary regions. Drawings are clipped to the 
intersection of two regions: the clip region (a user-maintained clipping region) and the vis 
region (a system-maintained clipping region). These work exactly as they do on the 
Macintosh. 
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The Drawing Environment 

The drawing environment is a set of rules which explain how drawing actions behave. The 
environment includes information about where drawing will occur (what part of memory, 
its chunkiness), in what coordinate system, how it will be clipped, the pen state, the font 
state and some other stuff. The various parts of die drawing environment are described 

below. 2 


Drawing Location 

QuickDraw H will draw anywhere in memory. The most common location may be the 
super hi-res screen, but a pixel map anywhere in memory and almost any size is acceptable 
as long as the entire destination pixel map is in a single bank. 

PortS CB — Hag to indicate chunldness of pixel map and master color palette. 

Pointer to die pixel map — points to the first byte in the pixel map. 

Width - num bytes in a row of pixels (QuickDraw term is rowBytes). 

Bounds Rectangle — Rectangle that describes the extent of the pixel map and 
imposes a coordinate system on it 

Port Rectangle - Rectangle that describes the active area of Data space. 

Pen State 


QuickDraw II maintains a graphics pen (position and size). Its position is used for drawing 
text and its size is used for determining the size of a frame. There are two kinds of 
drawing: normal drawing and erasing. In normal drawing, the destination pixel map 

depends on what it was to start with, the original fill pattern or pixel image and the drawing 

mode. 3 Erasing just fills the affected pixels with the background pattern. 


Pen Location - A point in data space. 


Pen Size - A point describing the width and height of the pen. 

Pattern Transfer Mode — One of the 8 transfer modes supported by the Primitives. 
This mode is used when drawing horizontal lines with the fill pattern. 


Pen Pattern — The pen pattern is used when drawing graphic objects. 

Drawing Mask — The drawing mask prevents pixels aligned with zeros in the mask 
from begin altered during drawing operations which use patterns. 


^The specific state of the display hardware (current color tables and SCBs) could also be 
though of as part of the environment, but for the purposes of this discussion we do not 
consider these. 

3 There are eight different drawing modes. These modes are rales used to derive die color 
of a pixel that is being drawn into. The eight modes and how they work are described in 
detail Appendix A. 
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Background Pattern - The background pattern is used when erasing graphic 
objects. 

Clipping 

As stated earlier, drawing is clipped to a variety of rectangles and regions. 

Other Stuff 

QuickDraw Us local environment includes clipping information, handles to pictures, 
regions and polygons, as well as a pointer to GrafPtocs record. The GrafProcs record is a 
record that holds pointers to all the standard drawing functions. A programmer may 
change the pointers in this record and cause different drawing routines to be used. 

An entire drawing environment is kept in a single record (called the GrafPort) which can be 
saved and restored with a single call This allows for simple (and hopefully fast) context 
switching. The GrafPort is a private data structure. The programmer can only change it by 
making calls to QuickDraw procedures which affect it 

Note: 

This is different from QuickDraw on the Macintosh today where you can change 
fields in the GrafPort directly. (Macintosh QuickDraw will most likely evolve to 
this in the future.) The full GrafPort definition is provided for debugging purposes 
but programs should not rely on fields staying in the same place within the record. 


Data Structures 

Fixed Point or Fixed 

F long integer where high word represents a integer value and low word is a 
fractional value. Fractional part is always positive (for example $8000 is 
one half). 


Pointer 

P long integer (highest byte must be zero) 

Handle 

H long integer (highest byte must be zero) 

Point 

V integer 

H integer 


Rect 

VI integer 

HI integer 

V2 integer 

H2 integer 
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String 


Standard ProDOS string starting with a length byte followed by up to 255 
characters of data. 

CString 

ASCH characters terminated with a zero byte. 

An_SCB_Byte 

Bits Meaning 


0-3 Color Table 

4 Reserved 

5 RU 0=off Ison 

6 Interrupt 0 = off 1 = on 

7 ' Color Mode 0=320 1=640 

ColorValue 

Blue: 0..15 
Green: 0..15 
Red: 0..15 
Reserved 0..15 

Total size is one word. The word is arranged as follows: 
I x | R | G | B | 


high low 

byte byte 


ColorTable 

packed array [0..15] of ColorValue 
Loclnfo 

PortS CB : an__scb„byte 
reserved-: byte 

PointerToPixellmage: pointer 
Width: integer 
BoundsRect: reel 

The width represents the number of bytes in a row (slice) of the pixel map. This number 
must be a multiple of 8. 

nibble = 0..15 
twobit = 0.3 
bit = 0..1 
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Pattern 


case mode of 

mode320: 

(packed array [0..63] of nibble); 
mode640: 

(packed array [0..63] of twobit); 


Mask 

packed array [0..63] of bit; 

TextS tyle 

word who© the following bits are defined: 
0 bold 

1 italic 

2 underline 

Bold and underline are supported in ROM. 

PenState 

PnLoc: point 
PnSize: point 
PnMode: integer 
PnPat: pattern 
PnMask: mask 
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GrafPort (Total Size is $AA or 170 bytes) 
Portlnfo: Loclnfo 
PortRect: net 
QipRgn: handle 
VisRgn: handle 
BkPat: Pattern 
PnLoc: Point 
PnSize: Point 
PnMode: integer 
PnPat: pattern 
PnMask: mask 
PnVis: integer 
FontHandle: Handle 
FondD: Long 
FontFlags: integer 
TxSize: integer 
TxFace: Style 
TxMode: integer 
SpExtra: fixed 
ChExtra: fixed 
FGColor: integer 
BGColor: integer 

PicSave: handle 
RgnSave: handle 
PolySave: handle 
GrafProcs: pointer 

ArcRot: integer 

UserField: long 
SysField: long 


Font 

See Appendix D 

FontlnfoRecord 

Ascent : integer 

Descent : integer 

WidMax : integer 

Leading : integer 

FontGlobalsRecord (currently 12 bytes long) 


fontID 

: integer 

style 

: textstyle 

size 

: integer 

version 

: VersionNumber 

widMax 

: integer 

fbrExtent 

: integer 
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BufSizeRecord (8 bytes long) 


Max Width : integer 

TextBufHeight : integer 

TextBufRowWords : integer 
FontWidth : integer 

Polygon 

PolySize : integer 

PolyBBox : tea 

PolyPoints : array [0..?] of point 

Cursor 

CursorHeight : integer 

CursorWidth* : integer 

Cursorlmage : [array 1 ..CursorHeight, 1..CursorWidth] of word 

CursorMask : [array 1.. CursorHeight, 1.. CursorWidth] of word 

HotSpotY : integer 

HotSpotX : integer 

"This is number of words wide of a single horizontal slice of the cursor. The last 
word in each slice of the cursor must be 0. 

Amor Cursor in 320 Mode: 

dc i’ll,4' ; eleven slices 

* ; by 4 words 

dc h'0000000000000000' ; cursor image 

dc h'Of00000000000000' 

dc h'OFFOOOOOOOOOOOOO' 

dc h'0FFF000000000000' 

dc h’OFFFFOOOOOOOOOOO* 

dc h'OFFFFFOOOOOOOOOO' 

dc h'OFFFFFFOOOO00000' 

dc h’0FFFFFFF00000000' 

dc h'0FF0FF0000000000’ 

dc h'00000FF000000000' 

dc h’0000000000000000' 

dc h’FF00000000000000' ; mask image 

dc h'FfFOOOOOOOOOOOOO 1 

dc h'FFFFOOOOOOOOOOOO' 

dc h’FFFFFOOOOOOOOOOO' 

dc h’FFFFFF0000000000' 

dc h'FFFFFFFOOOOOOOOO' 

dc h'FFFFFFFF00000000' 

dc h'FFFFFFFFF0000000' 

dc h'FFFFFFFF00000000' 

dc h'FFFOFFFFOOOOOOOO' 

dc h'00000FFF00000000' 

dc i'1,1' ; hot spot 
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The Calls 

Each of the calls listed below is listed in the form: 


ToolCall Brief description of the purpose of the function. 


Stack Before Call 

I previous contents 
I Space for Result 

I Pmml 

1 Paranl 

I 

Stack After Call 

I previous contents 
I The Result 

I 


I 

I Space for result (if any). 
I Description of parameter 
I Description of parameter 
k-SP 


I 

I Result (if any). 
k-SP 


Further description of the function and the parameters, if necessary. 

A call is made as follows: 

1. If the function has any output, push room for it on the stack. 

2. Push the inputs in the order listed. 

3. Invoke the macro for the call you want to make. The macro loads x with the 
appropriate value and executes a JSL to the tool dispatcher. 

4. If the function returned any output it is now at the top of the stack. 


Warning 

QuickDraw H is very unforgiving of certain kinds of programming errors. 

1) Making any QuickDraw calls without initializing QuickDraw First 

2) Passing any bad handles to QuickDraw 

• 3) Making any QuickDraw calls with a bad port 

Error codes are not likely to be returned when these three kinds of errors are made. In fact 
there is no guarentee that your program will get control ever again after making one of these 
errors. 

Unfortunately, a worse situation is that your program will appear to work for a while even 
though you make one of these errors but later die horribly for no reason. 
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Housekeeping Functions 


QDBootlnit Initializes QuickDraw II at boot time. The function puts the address 

of the cursor update routine into the bank El vectors. An application 
should never make this call. 

No Inputs. 


QDStartup Initializes Quickdraw II, sets the current port to the standard port, 

and clears the screen. 

Stack Before Call 

I previous contents 
I ZeroPageLoc 

I MasterSCB 

I MaxWidth 

I ProgrmdD 

I 

Stack After Call 

I previous contents I 
I k-SP 

QuickDraw uses three consecutive pages of bank zero for its zero page starting at the 
specified address. The MasterSCB is used to set all SCB's in the super hi-res graphics 
screen. MaxWidth is a number that tells QuickDraw II the size in bytes of the largest pixel 
map that will be drawn to (a value of zero indicates screen width). This allows QuickDraw 
II to allocate certain buffers it needs only once and keep them throughout the life of the 
application. PrograntID is the ID QuickDraw II will use when getting memory from the 
Memory Manager. All memory is reserved in the name of this ID. 

This call can fail for several reasons. The most common reasons are QuickDraw is already 
initialized, and there is not enough memory available for QuickDraw to obtain the buffers it 
needs. 

Warning: 

QuickDraw now uses three pages in bank zero. 

Error Codes 

Alreadylnitialized This is returned when an attempt is made to initialize 

QuickDraw a second time without shutting down first 

ScreenReserved This is returned when an the memory manager repor ts that 

the screen memory (bank El from $2000 to $9FFF) is 
already owned by someone else. 

Memory Manager Errors Any errors from the memory manager are returned 

unchanged. 


QDShutDown Frees up any buffers that were allocated. This call returns an error if 
QuickDraw is not active when the call was made. 

No Inputs. 


I integer 
I SCB (wad) 

I integer 

I User ID for memory manager (word). 
k-SP 


QuickDraw IIERS 


August 11,1986 


Page 13 




Possible Errors 

NotActive This is returned when an attempt is made to shutdown 

QuickDraw without ever starting it up. 

Memory Manager Errors Any errors from the memory manager are returned 

unchanged. 


QD Version Returns the version of QuickDraw IL 

Stack Before Call 

I previous contents 1 

I Space for Version I word 

I k-SP 

Stack After Call 

I previous contents I 

I Version I word 

I k-SP 


Possible Errors 
None. 


QDStatus Returns whether or not QuickDraw is active. 

Stack Before Call 

I previous contents I 

I Space for Status I Boolean (word) 

1 k-SP 

Stack After Call 

I previous contents I 

I Status I Boolean (word) 

I k-SP 


Possible Errors 
None. 
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GetStandardSCB Returns a copy of the standard SCB in the low byte of the word. 


Stack Before Call 

I previous contents I 

I Space for SCB I word 

I k-SP 

Stack After Call 

I previous contents I 

I SCB I word 

I k-SP 

The SCB has the following fields: 

Bits Meaning 

0-3 Color Table 0 

4 Reserved 

5 Fill off 

6 Interrupt off 

7 Color Mode = 320 


Possible Errors 


None. 


SetMasterSCB Sets the master SCB to the specified value (only the low byte is 
used). 


Stack Before Call 

I previous contents I 

I MasterSCB I Word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


The master SCB is the global mode byte used throughout QuickDraw H The master SCB 
is used by routines like InitPort to decide what standard values should be put into the 
GrafPort. 

Possible Errors 

None 
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GetMasterSCB Returns a copy of the master SGB (only the low byte is valid). 


Stack Before Call 

I previous contents I 

I Space MasterSCB I word 

I k-SP 

Stack After Call 

I previous contents I 

I MasterSCB I word 

I k-SP 


Possible Errors 
None 


InitColorTable Returns a copy of the standard color table for the current mode. 

Stack Before Call 

I previous contents I 

I TablePointer I Pointer to color table. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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The entries are as follows for 320 mode: 


Pixel Value 

Name 

Master Color 

0 

Black 

000 Opposite of White 

1 

Dark Gray 

7 7 7 

2 

Brown 

841 

3 

Purple 

72C 

4 

Blue 

OOF 

5 

Dark Green 

080 

6 

Orange 

f 7 0 

7 

Red 

D00 

8 

Flesh 

FA9 

9 

Yellow 

FF0 

10 

Green 

0E0 

11 

Light Blue 

4DF 

12 

Lilac 

DAF 

13 

Periwinkle Blue 

7 8 F 

14 

Light Gray 

CCC 

15 

White 

FFF Opposite of Black 

The entries are as follows for 640 mode: 

Pixel Value 

Name 

Master Color 

0 

Black 

000 

1 

Red 

F00 

2 

Green 

0F0 

3 

White 

FFF 

4 

Black 

000 

5 

Blue 

OOF 

6 

Yellow 

FF0 

7 

White 

FFF 

8 

Black 

000 

9 

Red 

F00 

A 

Green 

0F0 

B 

White 

FFF 

• C 

Black 

000 

D 

Blue 

OOF 

E 

Yellow 

FF0 

F 

White 

FFF 


For the rationale behind this color palette see Art Cabral's paper on Dithering Techniques 
640 mode. 


Possible Errors 


None. 


SetColorTable Sets a color table to specified values. 
Stack Before Call 
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I previous contents 
I TabkNwnber 

I DestPtPtr 

I 

Stack After Call 

I previous contents 

I 


I 

I integer 

I Pointer to color table 
k-SP 


I 

k-SP 


TableNumber identifies the table to be set to the values specified in the table pointed to. 
The 16 color tables are stored starting at $9E00. Each table takes $20 bytes. Each word 

the table represents one of 4096 colors. The high nibble of the high byte is ignored. 
Possible Errors 

BadTable Only Table numbers from 0 to 15 are valid. 


GetColorTable Fills a color table with the contents of another color table. 


Stack Before Call 

I previous contents 
I TableNumber 

I DestPtPtr 

I 


I 

I integer 

I Pointer to color table 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


TableNumber specifies the number of the color table whose contents are to be copied; 
TablePtr points to the color table which is to receive the contents. 

Possible Errors 

BadTable Only Table numbers from 0 to 15 are valid. 


SetColorEntry Sets the value of a color in a specified color table. 


Stack Before Call 

i previous contents 
I TableNumber 

I EntryNumber 

I NewCoior 

I 


I 

I integer 
I integer 
I integer 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 
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TableNumber specifies the number of the color table; EntryNwriber specifies the number 
of the color to be changed; Value sets the color. 

Possible Errors 

BadTable Only Table numbers from 0 to 15 are valid. 


GetColorEntry Returns the value of a color in a specified color table. 


Stack Before Call 

I previous contents 
I Space for Color 

I TableNumber 

I Entry Number 


I 

I word 
I integer 
I integer 
k-SP 


Stack After Call 

I previous contents I 

I Color I word 

I k-SP 


TableNumber specifies the number of the color table; EntryNwnber specifies the number 
of the color to be examined; Value returns die color. 

Possible Errors 

BadTable Only Table numbers from 0 to 15 are valid. 


SetSCB Sets the scan line control byte (SCB) to a specified value. 

Stack Before Call 


1 previous contents 

1 

1 ScanUm 

1 integer 

1 NewSCB 

1 integer 

1 

k-SP 

Stack After CaU 


1 previous contents 

1 

1 

k-SP 


Scanline identifies the scan line whose SCB is to be set; Value sets the SCB. 
Possible Errors 

BadScanLine Only scan line numbers from 0 to 199 are valid. 


GetSCB Returns the value of a specified scan line control byte (SCB). 

Stack Before Call 

I previous contents I 

I Space for SCB I word 
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I 

I 


ScmdJm 


I integer 
k-SP 


Stack After Call 

I previous contents I 
I SCB I word 

I k-SP 

Scanline identifies the son line whose SCB is to be examined; Value returns the value of 
die SCB. 

Possible Errors 

BadScanLine Only scan line numbers from 0 to 199 are valid. 


SetAllSCBs Sets all scan line control bytes (SCBs) to a specified value. 

Stack Before Call 

I previous contents 
I NewSCB 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 
None 


I 

I word 
k-SP 


I 

k-SP 


SetSysFont Tells QuickDraw to use the font passed as a system font 


Stack Before Call 

I previous contents I 

I FontHcmdk I Handle to font that will be system font 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 
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There is a default system font in ROM which will be used unless this call is made. A 
handle to the system font is put in the every port opened or inited. 

Possible Errors 

None 


GetSysFont 


Returns a handle to the current system font. 


Stack Before Call 

I previous contents I 

I Space for Handle I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I FontHandk I Handle 

I k-SP 


Possible Errors 


None 


ClearScreen Sets the words in the screen memory to the value passed. 

Stack Before Call 

I previous contents I 

1 ColorWonl I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


This is a very fast clear screen that just stuffs the value passed into each word of screen 
memory. The color you see on the screen will not be a solid color unless all the pixels in 
the word passed are the same. 

Possible Errors 

None 


GrafOn Turns on the super hi-res graphics mode. 

This routine only touches the bit in the NewVideo softswitch that affects the what is 
displayed. It does not change the linearization bit in the field. 

No Inputs. 
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Possible Errors 
None 

Graf Off Turns off the super hi-res graphics mode. 

This routine only touches the bit in the NewVideo softswitch that affects the what is 
displayed. It does not change the linearization bit in the field. 

No Inputs. 

Possible Errors 

None 
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GrafPort Calls 


OpenPort Initializes specified memory locations as a standard port and 

allocates new VisRgn and ClipRgn. 


Stack Before Call 

I previous contents 
I PortPtr 

I 


I 

I Pointer to Port. 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


InitPort Initializes specified memory locations as a standard port. 


Stack Before Call 

I previous contents 
I PortPtr 

I 


I 

I Pointer to Port. 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


InitPort, unlike OpenPort, assumes that the region handles are valid and does not 
allocate new handles. Otherwise, InitPort performs the same functions. 

Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


ClosePort Deallocates the memory associated with a port 


Stack Before Call 

I previous contents 

I PortPtr 

I 


I 

I Pointer to port 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 
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All handles are discarded. If the application disposes of the memory containing the port 
without first calling ClosePort, the memory associated with the handles is lost and cannot 
he claimed. 

Warning: Never close the current port 
Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


SetPort Makes the specified port the current port 


Stack Before Call 

I previous contents 
I .PonPtr 

I 

Stack After Call 

I previous contents 

I 


I 

I Pointer to port 
k-SP 


I 

k-SP 


Possible Errors 
None 


GetPort Returns the handle to the current port 


Stack Before Call 

I previous contents 
I Space for PonPtr 

I 

Stack After Call 

I previous contents 
I PortPtr 

I 

Possible Errors 
None 


I 

I Space for Pointer to port 
k-SP 


I 

I Pointer to port 
k-SP 


SetPortLoc Sets the current port's map information structure to the specified 

location information. 

Stack Before Call 

I previous contents I 

I Ptr to Lodnfo I Pointer 

I k-SP 

Stack After Call 
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I previous contents 

I 


I 

k-SP 


Possible Errors 
None 


GetPortLoc Gets the current port's map information structure and puts it at the 

address indicated. 

Stack Before Call 

I previous contents I 

I PtrtoLodnfo I Pointer 

I k-SP 

Stack After Call 

I previous contents " I 

I k-SP 

Possible Errors 

None 


SetPortRect Sets the current port's port rectangle to the specified recangle. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


GetPortRect Returns the current port's map port rectangle. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I ' k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 


None 


SetPortSize Qianges the size of the current GrafPort's PortRect 

Stack Before Call 


1 previous contents 

1 

1 width 

1 integer 

1 height 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

1 

k-SP 


This does not affect the pixel map, but just changes the active area of the GrafPort The 
call is normally used by the Window Manager. 

Possible Errors 

None 


MovePortTo Changes the location of the current GrafPort’s PortRect 

Stack Before Call 

I previous contents 
I H 

I V 

I 

Stack After Call 

I previous contents I 

I k-SP 

This does not affect the pixel map, but just changes the active area of the GrafPort The 
call is normally used by the Window Manager. 

Possible Errors 

None 


I 

I integer 
I integer 
k-SP 


SetOrigin Adjusts the contents of PortRect and BoundsRect so that the upper 

left comer of PortRect is set to the specified point 

Stack Before Call 

I previous contents I 
I H I integer 

I V I integer 

I k-SP 
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Slack After Call 

I previous contents I 

I k-SP 

VisRgn is also affected, but ClipRgn is not The pen position does not change. 

Possible Errors 

Memory Mgr Errors Any mors from the memory manage 1 are returned 

unchanged (The memory manage may be called when the 
VisRgn is offset). 


SetClip Sets the clip region to the region passed by using CopyRgn. 

Stack Before Call 

I previous contents I 

I RgnHandle I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

Memory Mgr Errors Any errors from the memory manage are returned 
unchanged 


GetClip Copies the Clip Region to the region passed The region must have 

been created earlie with a new rgn call. 

Stack Before Call 

I previous contents 
I RgnHandk 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 

Memory Mgr Errors Any errors from the memory manage are returned 
unchanged 


I 

I Handle 
k-SP 


I 

k-SP 


ClipRect Changes the clip region of the current GrafPort to a rectangle 

equivalent to a given rectangle. 

Stack Before Call 

I previous contents I 
I RectPtr I Pointer 
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I 


k-SP 


Stack After Call 

I previous contents I 
I k-SP 

This does not change the region handle, but affects the region itself. 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


HidePen Decrements the pen level. A positive pen level indicates drawing 

will occur, a negative pen level indicates drawing will not occur. 

No Inputs. 

Possible Errors 
None 


ShowPen Increments the pen level. A positive pen level indicates that drawing 

will occur; a negative pen level indicates drawing will not occur. 

No Inputs. 

Possible Errors 
None 


GetPen Returns the pen location. 

Stack Before Call 

I previous contents 
I PointPtr 
I 

Stack After Call 

I previous contents 
I 

Possible Errors 
None 


SetPenState Sets the pen state in the GrafPort to the values passed. 

Stack Before Call 


I 

I Pointer to point. 
k-SP 


I 

k-SP 


QuickDraw IIERS 


August 11,1986 


Page 28 



I previous contents 
I PenStatePtr 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 
None 


GetPenState Returns the pen state from the GrafPort 

Stack Before Call 

I previous contents 

I PenStatePtr 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 
None 


SetPenSize Sets the current pen size to the specified pen size. 

Stack Before Call 

I previous contents 
I width 

I height 

I 

, Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


I 

I integer 
I integer 
k-SP 


I 

I Pointer to PenState record. 
k-SP 


I 

k-SP 


I 

I Pointer to PenState record. 
k-SP 


I 

k-SP 


GetPenSize Returns the current pen size at the place indicated. 


Stack Before Call 

I previous contents I 

I PointPtr I Pointer to point. 

I k-SP 


Stack After Call 

I previous contents I 
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I 


k-SP 


Possible Errors 
None 


SetPenMode Sets the current pen mode to the specified pen mode. 


Stack Before Call 

I previous contents , I 

I PenMode I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 
None 


GetPenMode Returns the pen mode from the current port 

Stack Before Call 

I previous contents I 

I Space for PenMode I Space to PenMode (word). 

I k-SP 

Stack After Call 

I previous contents I 

I PenMode I word 

I k-SP 

Possible Errors 

None 


SetPenPat Sets the current pen pattern to the specified pen pattern. 

Stack Before Call 

I previous contents I 

I PattemPtr I Pointer to pattern. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 


None 


GetPenPat Returns the current pen pattern at the specified location. 

Stack Before Call 

I previous contents I 

I PattmtPo- I Pointer to pattern. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


SetSolidPenPat Sets the pen pattern to a solid pattern using the specified color. 

Stack Before Call 

I . previous contents I 

I ColorNtm I integer 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 



Stack Before Call 

I previous contents I 

I MaskPtr I Pointer to mask. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 


GetPenMask Returns the pen mask at the specified location. 

Stack Before Call 

I previous contents I 

I MaskPtr I Pointer to mask. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 






SUck Before Call 

I previous contents 



SUck Before Call 

I previous contents I 

I PattemPtr I Pointer to pattern. 

I k-SP 

SUck After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 


SetSolidBackPat Sets the background pattern to a solid pattern using the specified 
color. 

Stack Before Call 

I previous contents I 

I ColorNum I integer 

I k-SP 

Stack After Call 

I previous contents 1 

I k-SP 

Only an appropriate number of bits in ColorNwn are used. If the PortSCB indicates 320 
mode, then four bits are used; if the PortSCB indicates 640 mode, then two bits are used. 

Possible Errors 

None 


SolidPattern Sets the spcified pattern to a solid pattern using the specified color. 

Stack Before Call 

I previous contents 
I PanemPsr 

I ColorNum 

I 

Stack After Call 

I previous contents I 

I k-SP 

Only an appropriate number of bits in ColorNwn are used. If die PortSCB indicates 320 
mode, then four bits are used; if the PortSCB indicates 640 mode, then two bits are used. 

Possible Errors 

None 


I 

I Pointer 
I integer 
k-SP 


PenNormal Sets the pen state to the standard state (PenSize = 1,1; PenMode 

* copy; PenPat = Black; PenMask = l's). The pen location is not 
changed 


No Inputs. 
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Possible Errors 
None 


MoveTo Moves the current pen location to the specified point. 

Stack Before Call 

I previous contents I 

I H I integer 

I V I integer 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


Move Moves the current pen location by the specified horizontal and 

vertical displacements. 

Stack Before Call 

I previous contents I 

I dti I integer 

t <£/ I integer 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


SetFont Sets the current font to the specified font 

Stack Before Call 

I previous contents I 

I NewFontHandk I Handle to Font. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 


None 


GetFont Returns a handle to the current font 

Stack Before Call 

I previous contents I 

I Space for Result I Space for Handle. 

I k-SP 

Stack After Call 

I previous contents I 

I FontHandk I Handle 

I k-SP 

Possible Errors 

None 


SetFontID Sets the fontID field in the GrafPort 

Stack Before Call 

I previous contents I 

I NewFondD I FontID (long). 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

This routine does not change the current font All it does is set the font ID. This call is 
designed for use by the font manager for the benefit of the picture routines. The picture 
routines rise this field to try to find the font the application really wanted to draw with, 
rather than the one that was available when the picture was recorded 

Possible Errors 

None 


GetFontID Returns the FontID field in the GrafPort 

Stack Before Call 

I previous contents I 

I Space for Result I Space for FontID (long). 

I k-SP 

Stack After Call 

I previous contents I 

I FontHandk I FontID (long) 

I k-SP 
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Possible Errors 


None 


GetFontlnfo Returns information about the current font in the specified record. 

Stack Before Call 

I previous contents I 

I FIRecPtr I Pointer Fontlnfo record. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

The information in the FontlnfoRecord does not reflect current style modifications nor 
chExtra and spExtra. 

Possible Errors 

None 
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Stack Before Call 

I previous contents I 

I Space for integer I Space for resulting size 

I k-SP 

Stack After Call 

I previous contents I 

I are I integer 

I k-SP 

We expect that the amount of information returned by the GetFontGlobals call will change 
from version to version. This call makes it possible to find out how many bytes are being 
returned. 

For the version of QuickDraw in ROM, this value is 10. For the RAM patch (version 1.1) 
the value is 12. 

Possible Errors 

None 





record. 


Stack Before Call 

I previous contents I 

I FGRecPtr I Pointer FontGlobals record. 
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1 


k-SP 


Stack After Call 

I previous contents I 
I k-SP 

The size of the FontGlobals record is returned by the GetFGSize call. Hie infomation 
represents the grafport's current font, and does not reflect style modifications, chExtra or 
spExtr etc. Future versions of QuickDraw II may add mare information at the end of this 
record (see GetFGSize), but the current fields and their order will be maintained. 

Possible Errors 

None 




Stack Before Call 

I previous contents I 

I FontFktgs I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


The font flags are used to indicate special operations performed on the text Only one is 
defined at tins time. If the lowest bit of the word is set then the font will be considered a 
fixed with font (rather than proportional) and all characters will be equally spaced. The 
width of the characters is that of widMax. Other flags are reserved for future use. 

Possible Errors 

None 


Stack Before Call 

I previous contents 
I Space for Flags 

I 

Stack After Call 

I previous contents 
I FontFlags 


I Space for word. 
I<-SP 


I word 
l«-SP 
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Possible Errors 
None 


SetTextFace Sets the text face to the specified value. 

Stack Before Call 

I previous contents I 

I TextFace I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Up to sixteen operations are possible on the text (only two are supported in ROM). Each 
bit in the textface word represents a different face. Plain text has a text face of 0. 

Plain TextFace * 0 

Bold TextFace = 1 

Underline TextFace = 2 

Possible Errors 

None 


Stack Before Call 

I previous contents I 




I k-SP 

Stack After Call 

I previous contents I 

I TesFace I word 

I k-SP 

Possible Errors 

None 


SetTextMode Sets the text mode to the specified value. 

Stack Before Call 

I previous contents I 

I TextMode I word 

I k-SP 

Stack After Call 

I previous contents I 
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I k-SP 

There are eight different text transfer modes (and their opposites). The fastest modes are 
the modes which only transfer the foreground to the destination. The fastest of die 
foreground modes are FG-OR and FG-XOR. FG-BIC is almost as fast and FG-COPY is 
the slowest 

Possible Errors 

None 


GetTextMode Returns the current text mode. 


Stack Before Call 

I previous contents 
I Space for Result 
I 


I 

I Space for word. 
k-SP 


Stack After Call 

I previous contents I 

I TenMode I word 

I k-SP 


Possible Errors 
None 


SetSpaceExtra Sets the 

Stack Before Call 

I previous contents 
I SpaceExira 
I 

Stack After Call 
> I previous contents 

I 


space extra field in the grafport to the specified value. 


I 

I Fixed Point Value 
k-SP 


I 

k-SP 


The space extra is used by programs that are trying to justify text to a left and right 
boundry. When the space extra field is non zero, its value is added the width of each space 
printed in a string. It is a fixed point value rather than an integer because you want to be 
able to control this down to the last pixel 

Possible Errors 

None 


GetSpaceExtra Returns the space extra field from the grafport. 

Stack Before Call 

I previous contents I 
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I Space for Result I Space for Fixed Point Value. 

I l<-SP 

Stack After Call 

I previous contents I 

I SpaceExtra I LONG 

I k-SP 

Possible Errors 

None 


SetCharExtra Sets the char extra field in the grafport to the specified value. 

Stack Before Call 

I previous contents 
I ChtwExsu 
I 

Stack After Call 

I previous contents I 

I k-SP 

The CharExtra field in the grafport is used to add width to every character in the font that 
has width. It does not affect zero width characters. This field is present because some 
fonts that look good in one graphics mode need a little extra space between the characters in 
another mode. 

Possible Errors 

None 


I 

I Fixed Point Value 
k-SP 



Stack After Call 

I previous contents I 

I CharExsm I LONG 

I k-SP 

Possible Errors 


None 




SetForeCoIor Sets the foreground color field in the grafport to the specified value. 
Stack Before Call 
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I previous contents I 

I FereColor I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


GetForeColor Returns the current foreground color from the grafport 

Stack Before Call 

I previous contents I 

I Space for Result I Space for ForeColor (word). 

I k-SP 

Stack After Call 

I previous contents I 

I ForeColor I word 

I k-SP 

Possible Errors 

None 


SetBackColor Sets the background color field in the grafport to the specified value. 


Stack Before Call 

I previous contents I 

I BackColor I word 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 
None 



I previous contents 
I Space for Result 
I 


I 

I Space for BackColor (word). 
k-SP 


Stack After Call 

I previous contents 1 
I BackColor I word 
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I 


k-SP 


Possible Errors 
None 


SetBufDims This sets the size of the QuickDraw II clipping and text buffers. It 

overrides the MaxWidth value supplied to QDStartup and die text 
buffer defaults set at that time. 


Stack Before Call 


1 previous contents 

1 

1 MazWidih 

1 integer 

1 MaxFoniHeighi 

1 integer 

1 MaxFBRExtent 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

! 

k-SP 


MaxWidth is the width, in bytes, of the widest pixelmap the application will draw into (0 
indicates screen width). MaxFontHeight is the height of the tallest font the application will 
use (fRectHeight from the font record, computable as ascent + descent from the 
GetFontlnfo call). MaxFBRExtent is the greatest fbrExtent value of any font the 
application will use. fbrExtent is a field in the font record, and is returned by 
GetFontGlobals. It is defined as the greatest (horizontal) distance, in pixels, from the 
character origin to the furthest foreground or background pixel of any character in the font 
For more information, see "Fonts And Text In QuickDraw II". 

SetBufSize "pads" the text buffer to permit values of chExtra £ fbrExtent (of the currently 
active font), spExtra £ fbrExtent, and style modifications which add upto 36 pixels to the 
bounds width (width of foreground and background) of any character. 

When QDStartUp is called, it makes an internal call to SetBufDims, with the following 
values: 

MaxWidth as supplied by the application; 

MaxFontHeight ~2* (height of system font); 

MaxFBRExtent = 2 * (fbrExtent of system font). 

If the application does not use fonts larger than that, and only uses reasonable values of 
chExtra and spExtra and no very extreme (presumably customized) style modifications, 
then there is no reason to call SetBufDims or ForceBufDims. 


Error Codes 

Memory Manager Errors Any errors from the memory manager are returned 

unchanged. 
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ForceBufDims This call performs the same function as SetBufDims, except that. 

MaxFBRExtent value is not padded in any way. Any style 
modification, etc., that might increase the bounds width of a 
character must be added to MaxFBRExtent by the application. 


Stack Before Call 


1 previous contents 

1 

1 MaxWidth 

1 integer 

1 MaxFoniHeight 

1 integer 

1 MaxFBREMent 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

1 

k-SP 


This can be used to allow absurdly large values of chExtra, spExtra, strange styles, and the 
like. 

It is usually better to call SetBufDims and ForceBufDims once (if at all), early in the 
application with reasonable "max" values, because claiming and clearing a buffer can take 
lots of time. However, they may be called at any time. Also, it may sometimes be 
worthwhile to make one of these calls to shrink the size of the text buffer, thus conserving 
memory and (slightly) speeding performance. Don't be stingy, though. 


Error Codes 

Memory Manager Errors Any errors from the memory manager are returned 

unchanged. 


SaveBufDims This call saves QuickDraw's buffer sizing information in an 8 byte 
record supplied by the caller. 

Stack Before Call 

I previous contents I 

I Pointer to SkeJnfo 1 Pointer 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

This call can be used when an application (or tool) wants to temporarily change the size of 
the QuickDraw buffers but wants to be able to restore them as well. 

Possible Errors 

None 


RestoreBufDims This call restores QuickDraw's internal buffers to the sizes described 
in an 8 byte record. This record is created by SaveBufDims. 
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Stack Before Call 

I previous contents I 

1 MaxWidlh I integer 

I MaxFontHeight I integer 

I MaxFBRExtent I integer 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

This call can be used when an application (or tool) wants to temporarily change the size of 
the QuickDraw buffers but wants to be able to restore them as well. 

Error Codes 

Memory Manager Errors Any errors from the memory manager are returned 

unchanged. 


SetCIipHandle Sets the clip region handle field in the grafpart to the value passed. 

Stack Before Call 

I previous contents I . 

I RgnHmdk I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


Stack Before Call 

I previous contents I 

I Space for Resuit I Space for Handle 

I k-SP 


Stack After Call 

I previous contents I 

I RgnHandk I Handle 

I k-SP 
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Possible Errors 


None 


SetVisRgn 


Sets the vis region to the region passed by using CopyRgn. 


Stack Before Call 

I previous contents I 

I RgnHandk I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I < k-SP 


Possible Errors 
None 


GetVisRgn 


Copies the contents of the VisRgn into the region passed. The 
region must have been created earlier with a NewRgn call. 


Stack Before Call 

I previous contents I 

I RgnHandk I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 


None 


SetVisHan die Sets the clip region handle field in the graf port to the value passed. 

Stack Before Call 

I previous contents I 

I RgnHandk I Handle 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


QuickDraw IIERS 


August 11,1986 


Page 45 


Possible Errors 
None 


GetVisHandle Returns a copy of the handle to the VisRgn. 

Stack Before Call 

I previous contents I 

1 Space for Result I Space for Handle 

I k-SP 

Stack After Call 

I previous contents I 

I RgnHandk I Handle 

I k-SP 

Possible Errors 

None 




Stack Before Call 

I previous contents I 

I Space for Long I Space for PicSaveValue 

I k-SP 

Stack After Call 

I previous contents I 

I PicSaveValue I Long 

I k-SP 
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Possible Eirors 
None 


SetRgnSave Sets the RgnSave field to the value passed. This is an interal routine 

that should not be used by application programs. 

Stack Before Call 

I previous contents I 

I RgnSaveValm I LONG 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


GetRgnSave Returns the contents of the RgnSave field in the GrafPort. 

Stack Before Call 

I previous contents I 

I Space for Long I Space for RgnSaveValue 

I k-SP 

Stack After Call 

I previous contents I 

I RgnSaveValue I Long 

I k-SP 

Possible Eirors 

None 


SetPolySave Sets the PolySave field to the value passed. This is an interal 
routine that should not be used by application programs. 

Stack Before Call 

I previous contents I 

I PolySaveValue I Long 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 


GetPolySave Returns the contents of the PicSave field in the GrafPort 

Stack Before Call 

I previous contents I 

I Space for Long I Space for PolySaveValue 

I k-SP 

Stack After Call 

I previous contents I 

I PolySaveValue I Long 

I k-SP 

Possible Errors 

None 







Stack Before Call 

I previous contents I 

I GnfProcsPtr I Pointer 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


GetGrafProcs Returns the contents of the Pointer to the GrafProcs record 
associated with the GrafPort 

Stack Before Call 

I previous contents I 

I Space for Ptr I Space for Pointer to Graf Procs Record. 

I k-SP 


Stack After Call 

I previous contents 
I GrqfProesPtr 
I 


I 

I Pointer Graf Procs Record. 
k-SP 
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Possible Errors 


None 


SetUserField Sets the UserField field in the GrafPort to the value passed 
Programs can use this field to attach any data they want to a 
GrafPort by using this field as a pointer to some other data area. 

Stack Before Call 

I previous contents I 

I UserfieldValm I Long 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 




• 4. ii.TtiraaraRfsraBiOTraeratjwja 


Stack Before Call 

I previous contents I 

I Space for Long I Space for UserField Value 

I k-SP 

Stack After Call 

I previous contents I 

I UserField I Long 

I k-SP 

Possible Errors 

None 


SetSysField Sets the SysField field to the value passed This is an interal routine 

that should not be used by application programs. 

Stack Before Call 

I previous contents I 

I UsetfieldValm I Long 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 


GetSysField Returns the contents of the SysField field in the GrafPort 

Stack Before Call 

I previous contents I 

I Space for Long I Space for SysField Value 

I k-SP 

Stack After Call 

I previous contents I 

I SysField I Long 

I k-SP 

Possible Errors 

None 
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Drawing Calls 


LineTo Draws a line from the current pen location to the specified point 

Stack Before Call 

I previous contents I 

I H I integer 

I V I integer 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

Memory Mgr Errors If a region is open, LineTo commands contribute to the 

definition. Memory manager errors can occur at this time. 


Line Draws a line from the current pen location to a new point specified 

by die horizontal and vertical displacements. 

Stack Before Call 


1 previous contents 

i 

1 <H 

! integer 

1 dS 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

i 

k-SP 


Possible Errors 

Memory Mgr Errors If a region is open. Line commands contribute to the 

definition. Memory manager errors can occur at this time. 


Rectangle Drawing Calls 

FrameRect Draws the boundary of the specified rectangle with the current 

pattern and pen size. 

Stack Before Call 

I previous contents I 

I ReclPtr I Pointer to rectangle. 

I ' k-SP 

Stack After Call 

I previous contents I 

I k-SP 


QuickDraw IIERS 


August 11,1986 


Page 51 



Only points entirely within the rectangle are affected 
Possible Errors 

Memory Mgr Errors If a region is open, FrameRect commands contribute to the 
definition. Memory manager errors can occur at this time. 

PaintRect Paints (fills) the interior of the specified rectangle with the current 

pen pattern. 

Stack Before Call 

I previous contents I 

I ReaPP I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 

EraseReet Erases the interior of the specified rectangle with the background 

pattern. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 





11»« k #i iu! ») k'*\»■ i IT•Si 111 «(•) m •) m ft[** k s i tl- 1 a m ■- m r. \ a IUr- 


Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 

FillRect Paints (fills) the interior of the specified rectangle with the specified 

pattern. 

Stack Before Call 

I previous contents 
I RectPtr 

I PattmtPp 

I 

Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 

None 


I 

I Pointer to rectangle. 
I Pointer to pattern. 
k-SP 


Drawing Regions 



Stack After Call 

I previous contents I 

I k-SP 


Only points entirely inside the region are affected 


If a region is open and being formed the outside outline of the region being framed is 
added to that region's boundary. 


Possible Errors 


Memory Mgr Errors If a region is open, FrameRgn commands contribute to the 
definition. Memory manager errors can occur at this time. 


PaintRgn Paints (fills) the interior of the specified region with the current pen 

pattern. 

Stack Before Call 

I previous contents I 

I RgnHandk I Handle to region 

I k-SP 
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Stack After Call 

I previous contents 
I 

Possible Errors 
None 


EraseRgn Fills the interior of the specified region with the background pattern. 

Stack Before Call 

I previous contents I 

I RgnHcmdk I Handle to region 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


InvertRgn Inverts the pixels in the interior of the specified region. 

Stack Before Call 

I previous contents I 

I RgnHcmdk I Handle to region 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


k-SP 






Stack Before Call 

I previous contents I 

I RgnHcmdk I Handle to region 

I Patt&nPtr I Pointer to pattern 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 


None 

Drawing Polygons 


FramePoly Frames the specified polygon. 


Stack Before Call 

I previous consents 
I PotyHandk 
I 


I 

I Handle to polygon 
k-SP 


Stack After Call 

I previous contents 

I 


I 

k-SP 


Hie polygon is framed with a series of lineto calls. 
Possible Errors 


Memory Mgr Errors If a region is open, FramePoly commands contribute to die 
definition. Memory manager errors can occur at this time. 


PaintPoly Paints the specified polygon. 

Stack Before Call 

I previous contents I 

I PotyHandk I Handle to polygon 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 


He polygon is painted by opening a region, drawing lines, closing the region and painting 
the region. When the drawing is complete, the region is discarded. There must be enough 
memory around to hold the polygon. 

Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


ErasePoly 


Erases the specified polygon. 


Stack Before Call 

I previous contents 
I PotyHandk 

I 


I 

1 Handle to polygon 
k-SP 


Stack After Call 

I previous contents 
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I 


k-SP 


The polygon is erased by opening a region, drawing lines, closing the region and erasing 
the region. When the drawing is complete, the region is discarded. There must be enough 
memory around to hold the polygon. 

Possible Errors 

Memory Mjp’ Errors Any errors from the memory manager are returned 
unchanged. 


InvertPoly Inverts the specified polygon. 

Stack Before Call 

I previous contents I 

I PofyHandk I Handle to polygon 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

The polygon is inverted by opening a region, drawing lines, closing the region and 
inverting the region. When the drawing is complete, the region is discarded. There must 
be enough memory around to hold the polygon. 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


FillPoly Paints the specified polygon. 

Stack Before Call 

I previous contents 
I PofyHandk 

, I PastsnPtr 

I 

Stack After Call 

I previous contents I 

I k-SP 

The polygon is painted by opening a region, drawing lines, closing the region and painting 
the region. When the drawing is complete, the region is discarded. There must be enough 
memory around to hold the polygon. 


I 

I Handle to polygon 
I Pointer to pattern 
k-SP 
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Possible Eirors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


Oval Drawing Calls 


The code that draws ovals resides in RAM. The code that handles the ovals contribution to 
region definitions resides in ROM. 

FrameOval Draws the boundary of the oval enscribed in the specified rectangle 

with the current pattern and pen sire. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


Only points entirely within the rectangle are affected. 

Possible Errors 

Memory Mgr Errors If a region is open, FrameOval commands contribute to the 
definition. Memory manager errors can occur at this time. 

PaintOval Paints (fills) the interior of the oval enscribed in the specified 

rectangle with the current pen pattern. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 

EraseOval Erases the interior of the oval enscribed in the specified rectangle 

with the background pattern. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I k-SP 
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Stack After Call 

I previous contents 

I • 

Possible Errors 
None 

InvertOval Inverts the pixels in the interior of the oval enscribed in the specified 

rectangle. 

Stack Before Call 

I previous contents I 

I ReaPtr I Pointer to rectangle. 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 

FillOval Paints (fills) the interior of the oval enscribed in the specified 

rectangle with the specified pattern. 

Stack Before Call 

I previous contents I 

I RectPtr I Pointer to rectangle. 

I PattemPtr I Pointer to pattern. 

I k-SP 

Stack After Call 

I previous contents I 

1 k-SP 

Possible Errors 

None 


RoundRect Drawing Calls 

The code that draws roundrects resides in RAM. The code that handles the roundrects 
contribution to region definitions resides in ROM. 

FrameRRect Draws the boundary of the roundrect enscribed in the specified 

rectangle with the current pattern and pen size. 

Stack Before Call 

I previous contents 
I RectPtr 

I OvalWidth 

I OvalHeight 


Pointer to rectangle, 
integer 
integer 
<-SP 


I 

k-SP 
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Stack After Call 

I previous contents 
I 


l<-SP 


Only points entirely within the rectangle are affected. 

Possible Errors 

Memory Mgr Errors If a region is open, FrameRRect commands contribute to the 
definition. Memory manager errors can occur at this time. 

PaintRRect Paints (fills) the interior of the roundrect enscribed in the specified 

rectangle with the current pen pattern. 

Stack Before Call 

I previous contents 
I ReaPtr 

I OvalWidth 

I OvalHeight 

I 

Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 

None 


I 

I Pointer to rectangle. 
I integer 
I integer 
k-SP 




rectangle with the background pattern. 


Stack Before CaU 

I previous contents I 

I ReaPtr I Pointer to rectangle. 

I OvalWidth 1 integer 

I OvalHeight I integer 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 


None 


InvertRRect Inverts the pixels in the interior of the roundrect enscribed in the 

specified rectangle. 

Stack Before Call 

I previous contents 
I ReaPtr 

I OvalWidth 

I OvalHeight 


Pointer to rectangle, 
integer 
integer 
<-SP 
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Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 

None 

FillRRect Paints (fills) the interior of the roundrect enscribed in the specified 

rectangle with the specified patten. 

Stack Before Call 

I previous contents 
I RectPtr 

I OvdWidih 

I OvalHeight 

I PattmtPer 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 
None 


I Pointer to rectangle. 
I integer 
I integer 
I Pointer to pattern. 
k-SP 


I 

k-SP 


Arc Drawing Calls 

Arcs are defined by a rectangle, a start angle (in degrees) and an arc angle (in degrees). 
The arc that is drawn is the part of the oval described by the rectangle starting at start angle 
and sweeping clockwise arc angle degrees. 


Framed arcs do not contribute to region definitions. 


The code that draws ovals resides in RAM. 

FrameArc Draws the boundary of the arc enscribed in the specified rectangle 

with the current pattern and pen size. 


Stack Before Call 

I previous contents 
I RectPtr 

I StartAngle 

I ArcAngle 

I 

Stack After Call 

I previous contents 
I 


I 

I Pointer to rectangle. 
I integer 
I integer 
k-SP 


I 

k-SP 
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Only points entirely within the rectangle are affected 

Possible Errors 

None 

PaintArc Paints (Ells) the interior of the are enscribed in the specified 

rectangle with the current pen pattern. 

Stack Before Call 

I previous contents 
I RectPtr 

I StartAngle 

I ArcAngle 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 

None 

EraseArc Erases the interior of the arc enscribed in the specified rectangle with 

the background pattern. 

Stack Before Call 

I previous contents 

I RectPtr 

I StartAngle 

I ArcAngle 

I 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 

InvertArc Inverts the pixels in the interior of the arc enscribed in the specified 

rectangle. 

Stack Before Call 

I previous contents 
I RectPtr 

I StartAngle 

I ArcAngle 

I 

Stack After Call 

I previous contents 
I 


I 

I Pointer to rectangle. 
I integer 
I integer 
k-SP 


I 

k-SP 


I 

I Pointer to rectangle. 
I integer 
I integer 
k-SP 


I 

I Pointer to rectangle. 
I integer 
I integer 
k-SP 


I 

k-SP 
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Possible Errors 


None 

FillArc Paints (fills) the interior of the arc enscribed in the specified 

rectangle with the specified pattern. 

Stack Before Call 

I previous contents 
I ReaPtr 

I StartAngle 

I ArcAngle 

I PasemPtr 

I 

Stack After Call 

I previous contents 

I 

Possible Errors 
None 


I Pointer to rectangle. 
I integer 
I integer 
I Pointer to pattern. 
k-SP 


I 

k-SP 


Pixel Transfer Calls 


ScrollRect Shifts the pixels inside the intersection of the specified rectangle, 

VisRgn, ClipRgn, PortRect, and BoundsRect 


Stack Before Call 

I previous contents 
I RectPer 

I di 

I <N 

I UpdateRgnHandk 
I 


I Pointer to reel. 
I integer 
I integer 
I Handle 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


The pixels are shifted a distance of dh horizontally and dv vertically. The positive 
directions are to the right and down. No other pixels are affected. Pixels shifted out of the 
scroll area are lost The backgound pattern fills the space created by the scroll. In addition 
UpdateRgn is changed to the area filled with BackPat. 

Note that this UpdateRgn must be an existing region; it is not created by ScrollRect 
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Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


PaintPixels 

Stack 

I 

I 

I 


Transfers a region of pixels. 

Before Call 
previous contents I 

PamtParwnPn- I Pointer param block. 

k-SP 


Stack After Call 

I previous contents I 
I . k-SP 


PtuntParamPtr is equal to die following: 


PtrToSourceLodnfo 

Pointer 

PtrToDestLodnfo 

Pointer 

PtrToSourceRect 

Pointer 

PtrToDestRect 

Pointer 

Mode 

WORD 

MaskHandk (ClipRgn) 

Handle 


The pixels are transferred without referencing the current GrafPort. The source and 
destination are described in the input, as is the clipping region. 

A DestRect is required, but only die upper left comer is used in this version. In future 
versions we hope to be able to provide stretching and shrinking. The DestRect shoudl be 
the same size as the SrcRect for the code to work without changes in the future. 

Possible Errors 

NotEqualChunkiness This is returned when the source and destination pixel maps 
are not the same type. That is one is for a 320 mode display 
and one is for a 640 mode display. The type is determined 
by the PortSCB of the Loclnfo record. 


PPToPort Transfers pixels from a source pixel map to the current port clipping 

to the current Vis and Clip regions. 


Stack Before Call 

I previous contents 
I SrcLocPtr 
I SrcRect 

I DestX 

I DestY 

I Transfer Mode 


I Pointer param block. 

I Pointer source rectangle. 
I INTEGER. 

I INTEGER. 

I WORD. 
k-SP 


Stack After Call 
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I previous contents 

I 


k-SP 


This call differs form PaintPixels in that the current GrafPort is used as the destination. 
This is very useful when tring to paint a pixel map to a window and getting the clipping 
right. PaintPixels can do this but it requires extra code on the application's part 

Possible Errors 

NotEqualChunkiness This is returned when the source and destination pixel maps 
are not the same type. That is one is for a 320 mode display 
and one is for a 640 mode display. The type is determined 
by the PortSCB of die Loelnfo record. 


Text Drawing and Measuring 


All text is drawn in the current font starting at the current pen position using the current 
textmode and foreground and background colors. After text is drawn, the pen is advanced 
by the width of die text drawn. The amount of advance can be obtained from any of the 
width calls. The text box calls return a rectangle that is the bounding box for the text. This 
width of the bounding box is not necessarily the width of the characters drawn because of 
kerning. See the appendix on fonts for information on how this works. 


DrawChar 

Stack 

I 

I 

I 

Stack 

I 

I 


Draws the spedified character. 

Before Call 
previous contents I 

theCha- I word 

k-SP 

After Call 

previous contents I 

k-SP 


Possible Errors 
None 


DrawText Draws the spedified text 


Stack Before Call 

I previous contents 
I TeztPtr 

I TextLen 

I 

Stack After Call 


I 

I Pointer 
I integer 
k-SP 
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I previous contents 

I 


I 

k-SP 


Possible Errors 
None 


DrawString Draws die spedified siring. 

Stack Before Call 

I previous contents I 
I StringPtr I Pointer to port. 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 
None 


DrawCString Draws the spedified C-String. 

Stack Before Call 

I previous contents 
I StringPtr 
I 

Stack After Call 

i previous contents 

I 

Possible Errors 
None 


I 

I Pointer to port. 
k-SP 


I 

k-SP 


Width Calls 

Return the distance the pen would be advanced if the character or sequence of character 
were to be drawn. Reflects current style, chExtra, spExtra, etc. The actual pen position is 
not changed. 


CharWidth Returns the width of the spedified character. 

Stack Before Call 

I previous contents I 

I Space for width I Space for integer 

I theCitar I word 
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I 

Slack After Call 

I previous contents 
I width 

I 

Possible Errors 
None 


TextWidth Returns the width of the spedified text 

Stack Before Call 

I previous contents 
I Space for width 
I TextPtr 

I TextLen 

I 

Stack After Call 

I previous contents 
I width 

I 

Possible Errors 
None 


StringWidth Returns the width of the specified string. 

Stack Before Call 

I previous contents 
I Space for width 

I StringPtr 

I 

Stack After Call 

I previous contents 
I width 

I 

Possible Errors 

None 


CStringWidth Returns the width of the specified C-String. 

Stack Before Call 

I previous contents I 
I Space for width I Space for integer 

I CStnngPtr I Pointer 


I 

I Space for integer 
I Pointer 
k-SP 


I 

I integer 
k-SP 


I 

I Space for integer 
I Pointer 
I integer 
k-SP 


I 

I integer 
k-SP 


k-SP 


I 

I integer 
k-SP 
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I 


k-SP 


Stack After Call 

I previous contents I 

I width I integer 

I k-SP 

Possible Errors 

None 


Bounds Calls 

The Bounds calls set the contents of a specified rectangle so that rectangle is the smallest 
rectangle that encloses all the foreground and background pixels of the specified character 
or sequence of characters, if they were to be drawn. The rectangle is in local .coordinates. 
It is as tall as the font height, with ascent pixel rows above the current pen position and 
decent rows below. It extends as far to the left as the current pen position or as far as the 
leftmost kerning pixel, whichever is further to the left; and as far right as the (hypothetical) 
new pen position, or the rightmost kerning pixel, whichever is further right Reflects 
current style, chExtra, spExtra, etc. 

The rectangle is not actually drawn, and the actual pen position is not changed. 


CharBounds Sets the specified rectangle to be the bounds of the specified 

character. 

Stack Before Call 

I previous contents 
I theChar 

I RectPtr 

I 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


I 

I word 
I Pointer 
k-SP 


TextBounds Sets the specified rectangle to be the bounds of the specified text. 


Stack Before Call 

I previous contents 
I TextPtr 

I TextLen 

I RectPtr 

I 


I 

I Pointer to text 
I integer 
I Pointer to rect 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 
None 


StringBounds Sets the specified rectangle to be the bounds of specified string. 

Stack Before Call 

I previous contents 
I StrmgPtr 

I RectPtr 

I 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None 


I 

I Pointer to string. 
I Pointer to rect 
k-SP 


CStringBounds Sets the specified rectangle to be the bounds of specified cstring. 

Stack Before CaU 

I previous contents 
1 CStringPtr 

I RectPtr 

I 

Stack After Call 

I previous contents I 
I k-SP 


Possible Errors 
None 


I 

I Pointer to Cstring. 
I Pointer to rect 
k-SP 
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Various Utilities 
Calculations With Rectangles 

SetRect Sets the rectangle pointed to by RectPtr to the specified values. 


Stack Before Call 


1 previous contents 

1 

1 RectPtr 

1 Pointer 

1 Left 

1 integer 

1 Top 

1 integer 

1 Right 

1 integer 

1 Bottom 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

1 

k-SP 


Possible Errors 
None. 


OffsetRect Offsets the rectangle pointed to by RectPtr by the specified 

displacements. 


Stack Before Call 


1 previous contents 

i 

1 RectPtr 

1 Pointer 

1 cH 

1 integer 

1 & 

1 integer 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

i 

k-SP 


dv is added to the top and bottom; dh is added to the left and right 
Possible Errors 
None. 


InsetRect Insets the rectangle pointed to by RectPtr by the specified 

displacements. 

Stack Before Call 

I previous contents I 
I RectPtr I Pointer 

I di I integer 

I <N I integer 
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I 


k-SP 


Stack After Call 

I previous contents I 
I k-SP 

dv is added to the top and subtracted from the bottom; dh is added to die left and subtracted 
from the right. 

Possible Errors 

None. 


SectRect Calculates the intersection of two rectangles and places the 

intersection in a third rectangle. 


Stack Before Call 

I previous contents 
I space for result 

I RectPtr 

I RectPtr 

I RectPtr 

I 

Stack After Call 

I previous contents 
I Empty Flag 
I 


I Space for Boolean empty flag 
I Pointer 
I Pointer 
I Pointer 
k-SP 


I 

I Boolean (word). 
k-SP 


If the result is non-empty, the output is TRUE; if the result is empty, the output is FALSE. 

Possible Errors 
None. 

UnionRect Calculates the union of two rectangles and places the union in a third 

rectangle. 

Stack Before Call 

I previous contents 
I RectPtr 

I RectPtr 

I RectPtr 

I 

Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 
None. 

PtlnRect Detects whether a specified point is in a specified rectangle. 


I 

I Pointer to source rect 
I Pointer to source rect. 

I Pointer to destination rect 
k-SP 
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Stack Before Call 

I previous consents I 

I Space for Result I Space for Boolean result 

I PointPtr I Pointer 

I RectPtr I Pointer 

I k-SP 

Stack After Call 

I previous contents I 

I Result Flag I Boolean (word) result 

I k-SP 


For example: 

PtInRect((10,10)),((10,10,20,20)) is TRUE but 

PtInRect((20,20)),((l(U0,20,20)) is FALSE. 

Possible Errors 

None. 

Pt2Rect Copies one point to the upper left of a specified rectangle and 

another point to the lower right of the rectangle. 

Stack Before Call 

I previous contents 
I PointlPtr 

I PanUPtr 

I RectPtr 

I 

Stack After Call 

I previous contents I 
i k-SP 


Possible Errors 
None. 

EqualRect Compares two rectangles and returns TRUE or FALSE. 

Stack Before Call 

I previous contents 
I Space for Result 

I RectlPtr 

I RectlPtr 

I 

Stack After Call 

I previous contents 

I Boolean result I Boolaean (word) result. 

I k-SP 


I Space for Boolaean (word) result 
I Pointer to one rect 
I Pointer to other rect 
k-SP 


1 

I Pointer to source point 
I Pointer to source point 
I Pointer to destination rect 
k-SP 
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Possible Errors 


None. 


EmptyRect Returns whether or not a specified rectangle is empty. 


Stack Before Call 

I previous contents 
I Space for Result 
I RectPtr 

I 


I 

I Space for Boolean (word) result 

I Pointer 

k-SP 


Stack After Call 

I previous contents I 

I Result Flag I Boolean (word) result 

I k-SP 


An empty rectangle has the top greater than or equal to the bottom, or the left greater than or 
equal to the right 

Possible Errors 


None. 


Calculations With Points 


AddPt Adds two specified points together and leaves the result in the 

destination point 


Stack Before Call 

I previous contents 
I SrcPtPtr 

I DestPtPtr 

I 


I 

I Pointer to point 

I Pointer to point used as source and destination 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


Possible Errors 


None. 


SubPt Subtracts the source point from the destination point and leaves the 

result in the destination point 


Stack Before Call 

I previous contents 
I SrcPtPtr 

I DestPtPtr 

I 


I 

I Pointer to point 

I Pointer to point used as source and destination 
k-SP 
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Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None. 


SetPt Sets a point to specified horizontal and vertical values. 

Stack Before Call 

I previous contents 
I SrcPtPtr 

I H 

I V 

I 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None. 


EqualPt Returns a boolean result indicating whether two points are equal. 

Stack Before Call 

I previous contents 
I Boolean Result 
I SrcPtPtr 

I DestPtPtr 

I 

Stack After Call 

I previous contents I 

I Boolean Result I result 

I k-SP 

Possible Errors 
None. 


LocalToGlobal Converts a point from local coordinates to global coordinates. 

Stack Before Call 

I previous contents I 

I PomtPtr I Pointer to point 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 


Space for result 
Pointer to point 

Pointer to point used as source and destination 
-SP 


I Pointer to point 
I Horizontal value of point 
I Vertical value of point 
k-SP 
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Local coordinates are based on the current BoundsRect of the GrafPort Global 
coordinates have 0,0 as the upper left coma- of the pixel image. 

Possible Errors 

None. 




Stack Before Call 

I previous contents 

I PointPtr 

I 


I Pointer to point. 
k-SP 


Stack After Call 

I previous contents 


k-SP 


— 


Possible Errors 


None. 


Calculations With Regions 


NewRgn Allocates space for a new region and initializes it to the empty 

region. 

Stack Before Call 

I previous contents I 




I k-SP 

Stack After Call 

I previous contents I 

I Handle to NewRgn I Resulting Handle. 

I k-SP 

This is the only way to create a new region. All other calls work with existing regions. 
Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


DisposeRgn Deallocates space for the specified region. 

Stack Before Call 

I previous contents I 
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I RgnHemdk 

I 


I Handle to Region being disposed. 
k-SP 


Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


CopyRgn 


Copies the contents of a region from one region to another. 


Stack Before Call 

I previous contents 
I SrcRgnHandle 
I DestRgnHandk 

I 


I 

I Handle to source region. 

I Handle to destination region 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


If the regions are not the same size to start with, the DestRgn is resized. (DestRgn must 
already exist This call does not allocate it) 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


SetEmptyRgn Destroys the previous region information by setting it to the empty 
region. 

Stack Before Call 

I previous contents I 

> I RgnHmdk I Handle to Region being modified 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

The empty region is a rectangular region with a bounding box of (0,0,0,0). If the original 
region was not rectangular, the region is resized. 
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Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


SetRectRgn Destroys the previous region information by setting it to a rectangle 

described by the input. 


Stack Before Call 

I previous contents 
I RgnHcmdk 

I Left 

I Top 

I Right 

I Bottom 

I 


I Handle to region being set. 
I integer 
I integer 
I integer 
I integer 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


If the inputs do not describe a valid rectangle, the region is set to the empty region. If the 
original region was not rectangular, the region is resized. 

Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


RectRgn 


Destroys the previous region information by setting it to a rectangle 
described by the input 


Stack Before Call 

I previous contents I 

I RgnHandk I Handle to region being set 

I RectPtr I Pointer to rectangle used as source 

I k-SP 


Stack After Call 

I previous contents I 

I k-SP 


If the input does not describe a valid rectangle, the region is set to the empty region. If the 
original region was not rectangular, the region is resized. 

Possible Errors 


Memory Mgr Errors Any errors from the memory manager Me returned 
unchanged. 


OpenRgn Tells QuickDraw II to allocate temporary space and start saving lines 

and framed shapes for later processing as a region definition. 


No Inputs. 
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This call takes no inputs. Instead it allocates memory to hold information about the being 
created. When CloseRgn is called, the region is created and this memory is freed. 

While the region is open, all calls to Line, LineTo, FrameRect, FrameOval, 
FrameRRect, FrameRgn and FramePoly contribute to the region definitition. 

Possible Errors 

RgnAkeadyOpen This is returned if you are already saving to a region in this 
grafporL 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


CloseRgn 


Tells QuickDraw II to stop processing information and to return the 
region that has been created. 


Stack Before Call 

I previous contents 
I RgnHandle 

I 


I 

I Handle to region being set to collection of points 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


The region must already exist, and its contents are replaced with the new region. 


Possible Errors 


RgnNotOpen This is returned when there is not a region open in the 

current grafporL 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


OffsetRgn Moves the region on the coordinate plane a distance of dh 

horizontally and dv vertically. 

Stack Before Call 

I previous contents 
I RgnHandk 

I <M 

I <N 

I 

Stack After Call 

I previous contents I 

I k-SP 

The region retains its size and shape. 


I 

I Handle to region being offset 
I Horizontal displacement. 

I Vertical displacement. 
k-SP 
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Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged 


InsetRgn 


Shrinks or expands a region. 


Stack Before Call 

I previous contents 
I RgnHmdk 

I (H 

I a/ 

I 


I 

I Handle to region being inset 
I Horizontal displacement 
I Vertical displacement 
k-SP 


Stack After Call 

I previous contents 

I 


I 

k-SP 


All points on the region boundary are moved inwards a distance of dv vertically and dh 
horizontally. If dv or dh are negative, the points are moved outwards in that direction. 
InsetRgn leaves the region "centered" on the same position, but moves the outline. 
InsetRgn of a rectangular region works just like InsetRecL 


Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged 


SectRgn Calculates the intersection of two regions and places the intersection 

in the third region. 

Stack Before Call 

I previous contents 
I RgnHondkl 

I RgnHmdlel 

I DestRgnHandk 

I 

Stack After Call 

I previous contents I 
I k-SP 

The destination region must already exist The function does not allocate it However, the 
destination region may be one of the source regions. 

If the regions do not intersect, or one of the regions is empty, the destination is set to the 
empty region. 


I 

I Handle to one source region 
I Handle to another source region 
I Handle to destination region 
k-SP 
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Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged 


tJnionRgn Calculates the 

union of two regions and places the union in the third 

region* 


Stack Before Cal! 


1 previous contents 

1 

1 RgnHandlel 

1 Handle to one source region 

1 RgnHandlel 

1 Handle to another source region 

1 DestRgnHandle 

1 Handle to destination region 

1 

k-SP 

Stack After Call 


1 previous contents 

1 

1 

k-SP 


The destination region must already exist The function does not allocate it However, the 
destination region may be one of the source regions. 

If both regions are empty, the destination is set to the empty region. 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged 


DiffRgn Calculates the difference of two regions and places the difference in 

the third region. 

Stack Before Call 

I previous contents 
I RgnHandlel 

I RgnHandlel 

I DestRgnHandle 

I 

Stack After Call 

I previous contents I 
I k-SP 

The destination region must already exist. The function does not allocate it However, the 
destination region may be one of the source regions. 

If the source region is empty, the destination is set to the empty region. 


I 

I Handle to one source region 
I Handle to another source region 
I Handle to destination region 
k-SP 
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Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


XorRgn Calculates the difference between the union and the intersection of 

two regions and places the result in the third region. 

Stack Before Call 

I previous contents 
I RgnHandkl 

I RgnHandkl 

I DestRgnHandk 
I 

Stack After Call 

I previous contents I 
I k-SP 

The destination region must already exist The function does not allocate it However, the 

destination region may be one of the source regions. 

If the regions are not coincident the destination is set to the empty region. 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


I 

I Handle to one source region 
1 Handle to another source region 
I Handle to destination region 
k-SP 


PtlnRgn Checks to see whether the pixel below and to the right of the point is 

within the specified region. 

Stack Before Call 

I previous contents 
I Space for Result 

I PointPtr 

I RgnHandk 

I 

Stack After Call 

I previous contents I 

I Boolean Result I Boolean (word) 

I k-SP 

The function returns TRUE if the pixel is within the region and FALSE if it is not 
Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


I 

I Space for Boolean (word) 
I Pointer to point. 

I Region Handle 
k-SP 


RectlnRgn Checks whether a given rectangle intersects a specified region. 

Stack Before Call 
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I previous contents 
I Space for Result 

I RectPtr 

I RgnHandk 


Stack After Call 

I previous contents 
I Boolean Result 

I 


I Space for Boolean (word) 
I Pointer to rect 
I Region Handle 
k-SP 


I 

I Boolean (word) 
k-SP 


The function returns TRUE if the intersection encloses at least one pixel or FALSE if it 
does not 


Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


EqualRgn Compares the two regions and returns TRUE if they are equal or 

FALSE if not 


Stack Before Call 

I previous contents 
I Space for Result 

I RgnHandkl 

I RgnHandleZ 

I 


I 

I Space for Boolean (word) 
I Pointer to point 
I Region Handle 
k-SP 


Stack After Call 

I previous contents 
I Boolean Result 
I 


I 

I Boolean (word) 
k-SP 


The two regions must have identical sizes, shapes and locations to be considered equal. 
Any two empty regions are always equal 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


EmptyRgn Checks to see if a region is empty. 

Stack Before Call 

I previous contents 
I Space for Result 

I RgnHandk 
I 

Stack After Call 

I previous contents I 

I Boolean Result I Boolean (word) 

I k-SP 

Returns TRUE if the region is empty or FALSE if not 


1 

I Space for Boolean (word) 
I Region Handle 
k-SP 
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Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


Calculations with Polygons 


OpenPoly Returns a handle to a polygon data structure that win be updated by 

future LineTo's. 

Stack Before Call 

I previous contents I 

I Space for PotyHandte I Space for Handle to Polygon 

I k-SP 


Stack After Call 


I previous contents I 



Possible Errors 


PolyAlreadyOpen This is returned when a polygon is already open and being 
saved in the current gra^jort. 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


ClosePoly Completes the polygon creation process started with OpenPoly. 

Has no inputs or outputs. 

Possible Errors 

PolyNotOpen This is returned when a polygon is not open in the current 

grafport. 

Memory Mgr Errors Any errors from the memory'manager are returned 
unchanged. 


KillPoly Disposes of the specified polygon. 

Stack Before Call 

I previous contents I 

I PotyHandte I Handle to polygon 

1 k-SP 

Stack After Call 

I previous contents I 

I k-SP 
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Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


OffsetPoly Offsets the specified polygon by dH and dV. 

Stack Before Call 

I previous contents 
I PofyHaruHe 

I <H 

I <$/ 

I 

Stack After Call 

I previous contents 

I 


Possible Errors 


Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


I 

I Handle to polygon. 

I Horizontal displacement 
I Vertical displacement 
k-SP 


I 

k-SP 


Mapping and Scaling Utilities 


MapPt Maps the specified point from the source rect to the dest rect 

Stack Before Call 

I previous contents 
I PomtPB’ 

I SrcReaPtr 

I DestRectPtr 

I 

Stack After Call 

I previous contents I 
I k-SP 

Possible Errors 

None. 


I 

I Pointer to point 
I Pointer to source rect 
I Pointer to dest rect 
k-SP 


MapRect Maps the specified rectangle from the source rect to the dest rect 

Stack Before Call 

I previous contents 
I RectPtr 

I SrcReaPtr 

I DestRectPtr 


Stack After Call 
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Pointer to rectangle. 
Pointer to source rect 
Pointer to dest rect 




I previous contents 

I 


k-SP 


Possible Errors 
None. 


MapRgn Maps the specified region from the source rect to the dost rect 

Stack Before Call 

I previous contents 
I MapRgn 

I SrcRectPtr 

I DestRectPtr 

I 

Stack After Call 

I previous contents 

1 

Possible Errors 

Memory Mgr Errors Any errors from the memory manager are returned 
unchanged. 


I 

I Handle to region. 

I Pointer to source rect 
I Pointer to dest rect 
k-SP 


I 

k-SP 


MapPoly Maps the specified polygon from the source rect to the dest rect 

Stack Before Call 

I previous contents 
I PofyHandk 

I SrcRectPtr 

I DestRectPtr 

I 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 

None. 


I 

I Handle to polygon. 

I Pointer to source rect 
I Pointer to dest rect 
k-SP 


ScalePt 


Scales the specified point from the source rect to the dest rect. 


Stack Before Call 

I previous contents 

I PointPtr 

I SrcRectPtr 

I DestRectPtr 

I 

Stack After Call 

I previous contents 


I 

I Pointer to point. 

I Pointer to source rect 
I Pointer to dest rect 
k-SP 


k-SP 
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Possible Errors 


None. 


Miscellaneous Utilities 


Random Returns a pseudorandom number in the range -32768 to 32767, 

Stack Before Call 

I previous contents I 

I Space for integer I Space for returned integer 

I k-SP 

Stack After Call 

I previous contents I 

I Random integer I integer 

I k-SP 

The number returned is generated based upon calculations performed on SeedValue, which 
can be set with SetRandSeed. The result for any particular seed value is always the 
same. 

Possible Errors 
None. 


Stack Before Call 

I previous contents I 
I RandomSeed I long integer 

I k-SP 


Stack After Call 

I previous contents I 
I k-SP 

The algorithm for random numbers uses a 32 bit seed to produce a 16 bit random number. 
Possible Errors 


None. 


GetPixel Returns the pixel below and to the right of the specifed point 

Stack Before Call 

I previous contents I 

I Space for Pixel I Space for word 

I H I Horizontal value of point 

I V I Vertical value of point 

I k-SP 

Stack After Call 
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I previous contents 
I Pixel 


I word 
k-SP 


ThePbcel is returned in the lower bits of the word If the current drawing location has a 
chunkiness of 2, then 2 bits of the word are valid If the current drawing location has a 
chunkiness of 4, then 4 bits of the word are valid 

There is no guarantee that the point actually belongs to the port 

Possible Errors 

None. 
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Customizing QuickDraw Operations 

These routines work similarly to those in QuickDraw on the Macintosh. The major 
difference is that no inputs are passed on the stack. Instead the standard routines expea 
their inputs on zero page at particular locations. Moreover, they expect that QuickDraw's 
zero page is already switch©! in when they are called. Details on what parts of zero page 
are used for what are not available yet 

A final difference is how these routines are called. Rather than making standard tool calls, 
you access them through vectors in bank EO. 


SetStdProcs Sets up the specified record of pointers. 

Stack Before Call 

I previous contents I 

1 Pointer to StdProc Record I Pointer to standard proc record. 
I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Possible Errors 


None. 


StdText 

Draws standard text 

StdLine 

Draws standard lines. 

StdRect 

Draws standard rects. 

StdRRect 

Draws standard round rects. 

StdOval 

Draws standard ovals. 

StdArc 

Draws standard arcs. 

StdPoly 

Draws standard polys. 

StdRgn 

Draws standard regions. 

StdPixels 

Draws standard pixels. 
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StdComment 


Does standard comments for pictures. 


StdTxMeas 


Does standard text measuring. 


StdGetPic 


Does standard retieval from picture record. 


StdPutPic 


Does standard storage into picture record. 


SetlntUse 


Tells QuickDraw's cursor drawing code whether or not it should use 
scan line interrupts. 


Stack Before Call 


I 


I 


previous contents 
Usdnt 


I 

I word 
k-SP 


Stack After Call 

I previous contents I 

I k-SP 


QuickDraw normally uses scan line interrupts to draw the cursor without flicker. If an 
application wants to use scan line interrupts for some process of its own, it must tell 
QuickDraw not to use them. 


GetAddress Returns the address of the specified table. 


input 

output 

Stack Before Call 

I previous contents 
I Space for Pointer 
I D 

I 


2D WORD 

TablePtr LONG 


I 

I Space for Pointer to table in ROM 

I integer 

k-SP 


Stack After Call 

I previous contents I 

I k-SP 


The ID’s supported are 

1 ScreenTable 

2 ConTable320 

3 ConTable640 


QuickDraw H contains a number of tables that may be useful to a programmer. The 
GetAddress call is provided to make these tables accessable. It is absolutely imperitive that 
a program obtain the address of a table every time it runs. We will make no guarentee that 
these tables will stay in the same place when we change the ROM. In fact we can guarentee 
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that these tables will move and that anyone who hard-codes the addresses of these tables in 
their programs will be sorry. 

The screen table has 200 two byte entries. Each is the address of the start of a scan line in 
the display buffer. The zeroth entry is $2000, the address of scan line zero. Entry 1 is 
$20A0, the address of scan line one. And so on. 

ConTable320 and ConTable640 are used to convert from bytes that are one bit per pixel to 
bytes that are four and two bits per pixel respectively. ConTable320 has 256 four byte 
entries while ConTable640 has 256 two byte entries. These entries are the two and four bit 
per pixel representation of one bit per pixel bytes. For example, the byte containing $37 
looks as follows in one, two and four bit per pixel mode. 

One Bit Two Bit Four Bit 

%00110111 %00 0011 110011 11 11 $00FF 0FFF 

The two and four bit versions would be obtained from the table as follows: 



In both cases the addresses obtained from GetAddress are already on zero page. 
Possible Errors 


NotActive This is returned when QuickDraw has not been initialized. 


QuickDraw IIERS 


August 11,1986 


Page 88 



Cursor-Handling Routines 


SetCursor Sets the cursor to the image passed in the cursor record. 


Stack Before Call 

I previous contents 
I CursorPtr 

I 

Stack After Call 

I previous contents 

I 


I 

I Pointer to cursor record. 
k-SP 


I 

k-SP 


If the cursor is hidden, it remains hidden and appears in the new form when it becomes 
visible again. If the cursor is visible, it appears in the new form immediately. 


GetCursor Adr Returns a pointer to the current cursor record. 


Stack Before CaU 

I previous contents 
I Space for Pointer 

I 


I 

I Space for Pointer current cursor record. 
k-SP 


Stack After Call 

I previous contents 
I CursorPtr 
I 


I 

I Pointer to current cursor record 
k-SP 


HideCursor Decrements the cursor level. A cursor level of zero indicates the 

cursor is visible; a cursor level less than zero indicates the cursor is 
not visible. 

No Inputs. 


ShowCursor Increments the cursor level unless it is already zero. A cursor level 
of zero indicates the cursor is visible; a cursor level less than zero 
indicates the cursor is not visible. 

No Inputs. 


ObscureCursor Hides the cursor until the mouse moves. This tool is used to get the 
cursor out of the way of typing. 

No Inputs. 
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InitCursor 


Reinitializes the cursor. 


No Inputs. 

The cursor is set to the arrow cursor and made visible. Ibis routine also checks the 
MasterS CB and sets the cursor accordingly. This is the routine to use if for some reason 
you want to change modes in the middle of a program. The steps you take to do this are: 

1. Hide the cursor if it is not already hidden. 

2. Set the MasterSCB to the mode you want 

3. Set all the SCB's to the MasterSCB. 

4. Set the color table the way you want it 

5. Repaint the screen for the new mode 

6. Call InitCursor. 
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